package com.tianji.learning.service;

import com.tianji.learning.domain.po.PointsBoard;
import com.baomidou.mybatisplus.extension.service.IService;
import com.tianji.learning.domain.query.PointsBoardQuery;
import com.tianji.learning.domain.vo.PointsBoardVO;

import java.util.List;

/**
 * <p>
 * 学霸天梯榜 服务类
 * </p>
 *
 * @author zr
 * @since 2024-07-19
 */
public interface IPointsBoardService extends IService<PointsBoard> {

    /**
     * 根据查询条件获取积分榜信息。
     * <p>
     * 本方法通过接收一个PointsBoardQuery对象作为参数，查询并返回相应的积分榜信息。
     * 积分榜信息以PointsBoardVO对象的形式返回，包含了积分榜的详细数据。
     *
     * @param query 查询条件对象，包含对积分榜查询的特定条件，如赛季等。
     * @return 返回一个PointsBoardVO对象，其中包含了根据查询条件得到的积分榜信息。
     */
    PointsBoardVO queryPointsBoardBySeason(PointsBoardQuery query);

    /**
     * 根据赛季创建积分榜表
     * <p>
     * 本方法用于在数据库中根据指定的赛季创建一个新的积分榜表。这适用于赛季更迭时需要对数据进行分隔的情况，
     * 保证每个赛季的积分数据独立存储，便于统计和查询。
     *
     * @param season 赛季编号
     *               赛季编号是一个整数，用于唯一标识一个赛季。表名将根据此参数生成，确保每个赛季的表名唯一。
     *               注意：赛季编号应遵循一定的命名规则，以确保生成的表名合法且符合数据库的命名约束。
     */
    void createPointsBoardTableBySeason(Integer season);

    /**
     * 查询当前积分榜列表
     * <p>
     * 通过此方法可以查询与给定关键字相关联的积分榜列表。积分榜的展示是分页的，允许用户分批获取数据，
     * 从而减少单次数据传输的数量，提高应用的响应速度和用户体验。
     *
     * @param key      查询关键字。可以是任何与积分榜相关的标识或属性，用于过滤查询结果。
     * @param pageNo   当前页码。用于指定需要获取的分页数据的页码，起始页码为1。
     * @param pageSize 每页的记录数。用于指定每页显示的积分榜数量，控制分页数据的数量，影响查询性能。
     * @return 返回一个积分榜列表。列表中的每个元素都代表一个积分榜的详细信息，包括积分榜的排名、用户积分等。
     */
    List<PointsBoard> queryCurrentBoardList(String key, Integer pageNo, Integer pageSize);
}
